Summary

• add an opaque completion refresh token that correlates loading results, follow-up catalog events, and the originating completion task
• make completion tasks expose their refresh token synchronously so CodeMirror consumers can safely latch intent before caller-controlled reentrancy
• define precise token lifetimes for soft and terminal catalog-loading leases, including expiry, cancellation, update, and disposal
• harden AbortSignal handling against reentrant and throwing getters/listener methods without allowing an older invocation to erase newer work

Why

The upcoming CodeMirror adapter must refresh completion only for the request that originally produced a loading result. Revision checks alone cannot distinguish multiple requests at the same document revision, and asynchronous token publication leaves a race where catalog events can arrive before the consumer knows what to match. This contract makes that identity explicit and keeps latest-request-wins behavior correct across hostile caller boundaries.

Validation

• 2,003 tests pass; 1 intentional expected failure
• changed-file coverage: 97.92% statements, 96.01% branches, 100% functions, 98.01% lines
• all strict and loose-optional TypeScript configurations pass
• oxlint and test-integrity checks pass
• session completion benchmarks remain within budget
• two independent exact-commit adversarial reviews approved a0522c4

Summary by cubic

Adds an opaque completion refresh token to correlate loading results, follow-up catalog events, and the originating request. session.complete() now returns a SqlCompletionTask that exposes the token synchronously, and onDidChange events include the token when relevant.

• New Features

  • Introduced SqlCompletionRefreshToken and SqlCompletionTask (complete() returns a task with refreshToken).
  • SqlSessionChangeEvent now carries refreshToken:
    • catalog-availability: always includes the exact token for the active soft intent.
    • catalog: includes the matching token during an active intent lease, otherwise null.
    • provider-configuration: refreshToken is always null.
  • Ready results include refreshToken when a catalog-loading lease is active; otherwise null.
  • Hardened AbortSignal and timer handling to avoid reentrancy issues and prevent stale callbacks from erasing newer work.

• Migration

  • Update callers to use the new task:
    • const task = session.complete(...); const result = await task;
    • Use task.refreshToken immediately to latch intent.
  • Update onDidChange listeners:
    • Compare event.refreshToken to the latched task.refreshToken before refreshing.
    • Treat catalog events with refreshToken: null as unrelated to the current intent.
  • Adjust types:
    • complete() now returns SqlCompletionTask (still awaitable).
    • Handle the refined SqlSessionChangeEvent union with per-reason refreshToken semantics.
  • Do not serialize or introspect tokens; compare by identity only.

^{Written for commit a0522c4. Summary will update on new commits.}